home *** CD-ROM | disk | FTP | other *** search
/ Super Shareware Collection / Super Shareware Collection.iso / os_2 / clisp.zip / IMPNOTES.TXT < prev    next >
Text File  |  1994-02-05  |  50KB  |  1,414 lines
  1.                 Implementation Notes for CLISP
  2.                 ==============================
  3.                 Last modified: 1 September 1993.
  4.  
  5. This implementation is mostly compatible to the standard reference
  6.  
  7.        Guy L. Steele Jr.: Common Lisp - The Language (1st ed.).
  8.        Digital Press 1984, 465 pages.
  9.        ("CLtL1" for short)
  10.  
  11. and to the older parts of
  12.  
  13.        Guy L. Steele Jr.: Common Lisp - The Language (2nd ed.).
  14.        Digital Press 1990, 1032 pages.
  15.        ("CLtL2" for short)
  16.  
  17.  
  18. These notes document the differences of the CLISP implementation of Common
  19. Lisp to the standard CLtL1, and some implementation details.
  20.  
  21. The differences between CLtL1 and CLtL2 are made up of X3J13 votes. CLISP's
  22. position with respect to these votes is listed in defs2.lsp.
  23.  
  24.  
  25.                       CHAPTER 1: Introduction
  26.                       -----------------------
  27.  
  28. No notes.
  29.  
  30.  
  31.                        CHAPTER 2: Data Types
  32.                        ---------------------
  33.  
  34. All the data types are implemented: numbers, characters, symbols, lists,
  35. arrays, hash tables, readtables, packages, pathnames, streams, random
  36. states, structures and functions.
  37.  
  38. 2.1.3.
  39. ------
  40.  
  41. There are four floating point types: short-float, single-float, double-float
  42. and long-float:
  43.                   sign    mantissa   exponent
  44.    short-float    1 bit   16+1 bits   8 bits
  45.    single-float   1 bit   23+1 bits   8 bits   CLISP uses IEEE format
  46.    double-float   1 bit   52+1 bits  11 bits   CLISP uses IEEE format
  47.    long-float     1 bit   >=64 bits  32 bits
  48.  
  49. The single and double float formats are those of the IEEE standard (1981),
  50. except that CLISP does not support features like +0, -0, +inf, -inf, gradual
  51. underflow, NaN, etc. (Common Lisp does not make use of these features.)
  52.  
  53. Long floats have variable mantissa length, which is a multiple of 16 (or 32,
  54. depending on the word size of the processor). The default length used when
  55. long floats are read is given by the place (LONG-FLOAT-DIGITS). It can be
  56. set by (SETF (LONG-FLOAT-DIGITS) nnn), where nnn is a positive integer.
  57.  
  58. 2.1.4.
  59. ------
  60.  
  61. Complex numbers can have a real part and an imaginary part of different
  62. types. For example, (SQRT -9.0) evaluates to the number #C(0 3.0), which has
  63. a real part of exactly 0, not only 0.0 (which would mean "approximately 0").
  64. The type specifier for this is (COMPLEX INTEGER SINGLE-FLOAT), and
  65.  
  66.            (COMPLEX type-of-real-part type-of-imaginary-part)
  67.  
  68. in general.
  69. The type specifier (COMPLEX type) is equivalent to (COMPLEX type type).
  70.  
  71. 2.2.1.
  72. ------
  73.  
  74. The characters are ordered according to the ASCII encoding.
  75.  
  76. More precisely, CLISP uses the IBM PC character set (code page 437):
  77.              $0 $1 $2 $3 $4 $5 $6 $7 $8 $9 $A $B $C $D $E $F
  78.          $00 **                   ** ** ** ** ** ** **    
  79.          $10                               ** **            
  80.          $20     !  "  #  $  %  &  '  (  )  *  +  ,  -  .  /
  81.          $30  0  1  2  3  4  5  6  7  8  9  :  ;  <  =  >  ?
  82.          $40  @  A  B  C  D  E  F  G  H  I  J  K  L  M  N  O
  83.          $50  P  Q  R  S  T  U  V  W  X  Y  Z  [  \  ]  ^  _
  84.          $60  `  a  b  c  d  e  f  g  h  i  j  k  l  m  n  o
  85.          $70  p  q  r  s  t  u  v  w  x  y  z  {  |  }  ~  
  86.          $80  Ç  ü  é  â  ä  à  å  ç  ê  ë  è  ï  î  ì  Ä  Å
  87.          $90  É  æ  Æ  ô  ö  ò  û  ù  ÿ  Ö  Ü  ¢  £  ¥      
  88.          $A0  á  í  ó  ú  ñ  Ñ  ª  º  ¿     ¬  ½  ¼  ¡  «  »
  89.          $B0                                                
  90.          $C0                                                
  91.          $D0                                                
  92.          $E0     ß              µ                           
  93.          $F0     ±              ÷     °     ·        ²      
  94. Here ** are control characters, not graphic characters. (The characters left
  95. blank here cannot be represented in this character set).
  96.  
  97. The following are standard characters:
  98.   #\Space               $20
  99.   #\Newline             $0A
  100. The following are semi-standard characters:
  101.   #\Backspace           $08
  102.   #\Tab                 $09
  103.   #\Linefeed            $0A
  104.   #\Page                $0C
  105.   #\Return              $0D
  106.   #\Rubout              $08
  107.  
  108. 2.2.2.
  109. ------
  110.  
  111. #\Newline is the delimiter between lines.
  112.  
  113. When writing to a file, #\Newline is converted to CR/LF. (This is the usual
  114. convention on ATARI, DOS and VMS.) For example, #\Return #\Newline is written
  115. as CR/CR/LF.
  116. When reading from a file, CR/LF is converted to #\Newline, and CR not
  117. followed by LF is read as #\Return.
  118.  
  119. 2.2.3.
  120. ------
  121.  
  122. There are the following additional characters with names:
  123.   #\Null                $00
  124.   #\Bell                $07
  125.   #\Escape              $1B
  126.  
  127. 2.2.4.
  128. ------
  129.  
  130. The code of a character is >=0, <256. CHAR-CODE-LIMIT = 256.
  131.  
  132. There are fonts 0 to 15, and CHAR-FONT-LIMIT = 16. But the system itself
  133. uses only font 0.
  134.  
  135. The following bits attributes are implemented: :CONTROL, :META, :SUPER,
  136. :HYPER. Therefore CHAR-BITS-LIMIT = 16.
  137. The system itself uses these bits only to mention special keys and
  138. Control/Alternate/Shift key status on return from
  139. (READ-CHAR *KEYBOARD-INPUT*).
  140.  
  141. 2.5.
  142. ----
  143.  
  144. The maximum rank (number of dimensions) of an array is 65535 on 16-bit
  145. processors, 4294967295 on 32-bit processors.
  146.  
  147. 2.13.
  148. -----
  149.  
  150. All the functions built by FUNCTION, COMPILE and the like are atoms. There
  151. are built-in functions written in C, compiled functions (both of type
  152. COMPILED-FUNCTION) and interpreted functions (of type FUNCTION).
  153. The possible function names (CLtL1 p. 59) are symbols and lambda expressions.
  154.  
  155. 2.14.
  156. -----
  157.  
  158. This is the list of objects whose external representation can not be
  159. meaningfully read in:
  160.   * all structures lacking a keyword constructor.
  161.   * all arrays except strings, if *PRINT-ARRAY* = NIL.
  162.   * #<SYSTEM-FUNCTION name>     built-in function written in C
  163.   * #<SPECIAL-FORM name>        special form handler
  164.   * #<COMPILED-CLOSURE name>    compiled function, if *PRINT-CLOSURE* = NIL
  165.   * #<CLOSURE name ...>         interpreted function
  166.   * #<FRAME-POINTER #x...>      pointer to a stack frame
  167.   * #<DISABLED POINTER>         frame pointer which has become invalid on
  168.                                 exit from the corresponding BLOCK or TAGBODY
  169.   * #<...-STREAM ...>           stream
  170.   * #<PACKAGE name>             package
  171.   * #<HASH-TABLE #x...>         hash table, if *PRINT-ARRAY* = NIL
  172.   * #<READTABLE #x...>          readtable
  173.   * #<UNBOUND>                  "value" of a symbol without value, "value"
  174.                                 of an unsupplied optional or keyword argument
  175.   * #<SPECIAL REFERENCE>        environment marker for variables declared
  176.                                 SPECIAL
  177.   * #<DOT>                      internal READ result for "."
  178.   * #<END OF FILE>              internal READ result, when the end of file
  179.                                 is reached
  180.   * #<READ-LABEL ...>           intermediate READ result for #n#
  181.   * #<ADDRESS #x...>            machine address, should not occur
  182.   * #<SYSTEM-POINTER #x...>     should not occur
  183.  
  184. 2.15.
  185. -----
  186.  
  187. The type NUMBER is the disjoint union of the types REAL and COMPLEX. (CLtL
  188. wording: "exhaustive partition")
  189. The type REAL is the disjoint union of the types RATIONAL and FLOAT.
  190. The type RATIONAL is the disjoint union of the types INTEGER and RATIO.
  191. The type INTEGER is the disjoint union of the types FIXNUM and BIGNUM.
  192. The type FLOAT is the disjoint union of the types SHORT-FLOAT, SINGLE-FLOAT,
  193. DOUBLE-FLOAT and LONG-FLOAT.
  194.  
  195.  
  196.                      CHAPTER 3: Scope and Extent
  197.                      ---------------------------
  198.  
  199. is implemented as described.
  200.  
  201.  
  202.                       CHAPTER 4: Type Specifiers
  203.                       --------------------------
  204.  
  205. 4.5.
  206. ----
  207.  
  208. The general form of the COMPLEX type specifier is
  209. (COMPLEX type-of-real-part type-of-imaginary-part).
  210. The type specifier (COMPLEX type) is equivalent to (COMPLEX type type).
  211.  
  212. 4.6.
  213. ----
  214.  
  215. The REAL type specifier (REAL low high) denotes the real numbers between low
  216. and high.
  217.  
  218. 4.7.
  219. ----
  220.  
  221. DEFTYPE lambda lists are subject to destructuring (nested lambda lists are
  222. allowed, as in DEFMACRO) and may contain a &WHOLE marker, but no
  223. &ENVIRONMENT marker.
  224.  
  225. 4.9.
  226. ----
  227.  
  228. The possible results of TYPE-OF are:
  229.  CONS
  230.  SYMBOL NULL
  231.  FIXNUM BIGNUM RATIO SHORT-FLOAT SINGLE-FLOAT DOUBLE-FLOAT LONG-FLOAT COMPLEX
  232.  CHARACTER
  233.  (ARRAY element-type dimensions), (SIMPLE-ARRAY element-type dimensions)
  234.  (VECTOR T size), (SIMPLE-VECTOR size)
  235.  (STRING size), (SIMPLE-STRING size)
  236.  (BIT-VECTOR size), (SIMPLE-BIT-VECTOR size)
  237.  FUNCTION COMPILED-FUNCTION
  238.  STREAM PACKAGE HASH-TABLE READTABLE PATHNAME RANDOM-STATE
  239.  BYTE LOAD-TIME-EVAL SYMBOL-MACRO READ-LABEL FRAME-POINTER SYSTEM-INTERNAL
  240.  ADDRESS (should not occur)
  241.  any other symbol (structure types or CLOS classes)
  242.  a class (CLOS classes without proper name)
  243.  
  244.  
  245.                        CHAPTER 5: Program Structure
  246.                        ----------------------------
  247.  
  248. 5.1.3.
  249. ------
  250.  
  251. In addition to the 24 special forms listed on p. 57, the macros
  252. PSETQ, PROG1, PROG2, WHEN, UNLESS, COND, MULTIPLE-VALUE-LIST,
  253. MULTIPLE-VALUE-BIND, MULTIPLE-VALUE-SETQ, AND, OR
  254. are implemented as special forms.
  255.  
  256. Constants may not be bound dynamically or lexically.
  257.  
  258. 5.2.2.
  259. ------
  260.  
  261. LAMBDA-LIST-KEYWORDS =
  262.     (&OPTIONAL &REST &KEY &ALLOW-OTHER-KEYS &AUX &BODY &WHOLE &ENVIRONMENT)
  263.  
  264. LAMBDA-PARAMETERS-LIMIT is 65536 on 16-bit processors, 4294967296 on 32-bit
  265. processors.
  266.  
  267. 5.3.
  268. ----
  269.  
  270. DEFUN and DEFMACRO are allowed in non-toplevel positions.
  271. As an example, consider the definition of GENSYM:
  272. (let ((gensym-prefix "G")
  273.       (gensym-count 1))
  274.   (defun gensym (&optional (x nil s))
  275.     (when s
  276.       (cond ((stringp x) (setq gensym-prefix x))
  277.             ((integerp x)
  278.              (if (minusp x)
  279.                (error "~S: index ~S is negative" 'gensym x)
  280.                (setq gensym-count x)
  281.             ))
  282.             (t (error "~S: argument ~S of wrong type" 'gensym x))
  283.     ) )
  284.     (prog1
  285.       (make-symbol
  286.         (concatenate 'string
  287.           gensym-prefix
  288.           (write-to-string gensym-count :base 10 :radix nil)
  289.       ) )
  290.       (incf gensym-count)
  291. ) )
  292.  
  293. 5.3.2.
  294. ------
  295.  
  296. (PROCLAIM '(SPECIAL var)) declarations may not be undone. The same holds
  297. for DEFVAR, DEFPARAMETER and DEFCONSTANT declarations.
  298.  
  299. It is an error if a DEFCONSTANT variable is bound at the moment the
  300. DEFCONSTANT is executed, but DEFCONSTANT does not check this.
  301.  
  302. Constants may not be bound dynamically or lexically.
  303.  
  304.  
  305.                       CHAPTER 6: Predicates
  306.                       ---------------------
  307.  
  308. 6.2.2.
  309. ------
  310.  
  311. REALP returns T is its argument is a real number, NIL otherwise.
  312.  
  313. COMPILED-FUNCTION-P returns T on built-in functions written in C, compiled
  314. functions and special form handlers. Therefore COMPILED-FUNCTION is not a
  315. subtype of FUNCTION.
  316.  
  317. 6.3.
  318. ----
  319.  
  320. EQ compares characters and fixnums as EQL does. No unnecessary copies are
  321. made of characters and numbers. Nevertheless, one should use EQL.
  322.  
  323. (let ((x y)) (eq x x)) always returns T, regardless of y.
  324.  
  325. 6.4.
  326. ----
  327.  
  328. AND and OR are implemented as special forms and, as such, rather efficient.
  329.  
  330.  
  331.                       CHAPTER 7: Control Structure
  332.                       ----------------------------
  333.  
  334. 7.1.1.
  335. ------
  336.  
  337. (FUNCTION symbol) returns the local function definition established by FLET
  338. or LABELS, if it exists, otherwise the global function definition.
  339.  
  340. The CLtL2 place (FDEFINITION function-name) is implemented.
  341.  
  342. (SPECIAL-FORM-P symbol) returns NIL or T. If it returns T, then
  343. (SYMBOL-FUNCTION symbol) returns the (useless) special form handler.
  344.  
  345. 7.1.2.
  346. ------
  347.  
  348. PSETQ is implemented as a special form and, as such, rather efficient.
  349.  
  350. 7.2.
  351. ----
  352.  
  353. (SETF (SYMBOL-FUNCTION symbol) object) requires object to be either a
  354. function, a SYMBOL-FUNCTION return value or a lambda expression. A lambda
  355. expression is thereby immediately converted to a function.
  356.  
  357. SETF also accepts places yielding multiple values.
  358.  
  359. Additional places:
  360.  
  361. * FUNCALL:
  362.   (SETF (FUNCALL #'symbol ...) object) and
  363.   (SETF (FUNCALL 'symbol ...) object)
  364.   are equivalent to (SETF (symbol ...) object).
  365.  
  366. * GET-DISPATCH-MACRO-CHARACTER:
  367.   (SETF (GET-DISPATCH-MACRO-CHARACTER ...) ...)
  368.   performs a SET-DISPATCH-MACRO-CHARACTER.
  369.  
  370. * LONG-FLOAT-DIGITS:
  371.   (SETF (LONG-FLOAT-DIGITS) digits) sets the default mantissa length of long
  372.   floats to digits bits.
  373.  
  374. * VALUES:
  375.   (SETF (VALUES place1 ... placek) form)
  376.   is approximately equivalent to
  377.      (MULTIPLE-VALUE-BIND (dummy1 ... dummyk) form
  378.        (SETF place1 dummy1 ... placek dummyk)
  379.        (VALUES dummy1 ... dummyk)
  380.      )
  381.   Example:
  382.     (SETF (VALUES A B) (VALUES B A)) interchanges the values of A and B.
  383.  
  384. * VALUES-LIST:
  385.   (SETF (VALUES-LIST list) form)  is equivalent to
  386.   (VALUES-LIST (SETF list (MULTIPLE-VALUE-LIST form)))
  387.  
  388. &KEY markers in DEFSETF lambda lists are supported, but the corresponding
  389. keywords must appear literally in the program text.
  390.  
  391. (GET-SETF-METHOD form &optional env) and
  392. (GET-SETF-METHOD-MULTIPLE-VALUE form &optional env)
  393. receives as optional argument the environment necessary for macro expansions.
  394. In DEFINE-SETF-METHOD lambda lists, one can specify &ENVIRONMENT and a
  395. variable, which will be bound to the environment. This environment should be
  396. passed to all calls of GET-SETF-METHOD and GET-SETF-METHOD-MULTIPLE-VALUE.
  397. If this is done, even local macros will be interpreted as places correctly.
  398.  
  399. 7.3.
  400. ----
  401.  
  402. CALL-ARGUMENTS-LIMIT is 65536 on 16-bit processors, 4294967296 on 32-bit
  403. processors.
  404.  
  405. 7.4.
  406. ----
  407.  
  408. PROG1 and PROG2 are implemented as special forms and, as such, rather
  409. efficient.
  410.  
  411. 7.5.
  412. ----
  413.  
  414. The CLtL2 special form SYMBOL-MACROLET is implemented.
  415.  
  416. The macro DEFINE-SYMBOL-MACRO establishes symbol macros with global scope
  417. (as opposed to symbol macros defined with SYMBOL-MACROLET, which have local
  418. scope): (DEFINE-SYMBOL-MACRO symbol expansion). Calling BOUNDP, SYMBOL-VALUE
  419. or MAKUNBOUND on symbols defined as symbol macros is not allowed.
  420.  
  421. If using the optional package MACROS3:
  422.   The macros LETF and LETF* are like LET and LET*, resp., except that they
  423.   can bind places, even places with multiple values.
  424.   Example:
  425.   (LETF (((VALUES A B) form)) ...)
  426.     is equivalent to
  427.     (MULTIPLE-VALUE-BIND (A B) form ...)
  428.   (LETF (((FIRST L) 7)) ...)
  429.     is approximately equivalent to
  430.     (LET* ((#:G1 L) (#:G2 (FIRST #:G1)))
  431.       (UNWIND-PROTECT (PROGN (SETF (FIRST #:G1) 7) ...)
  432.                       (SETF (FIRST #:G1) #:G2)
  433.     ) )
  434.  
  435. 7.6.
  436. ----
  437.  
  438. WHEN, UNLESS, COND are implemented as special forms and, as such, rather
  439. efficient.
  440.  
  441. 7.8.4.
  442. ------
  443.  
  444. The function MAPCAP is like MAPCAN, except that it concatenates the
  445. resulting lists with APPEND instead of NCONC:
  446.   (MAPCAP fun x1 ... xn) == (apply #'append (mapcar fun x1 ... xn))
  447. (Actually a bit more efficient that this would be.)
  448.  
  449. The function MAPLAP is like MAPCON, except that it concatenates the
  450. resulting lists with APPEND instead of NCONC:
  451.   (MAPLAP fun x1 ... xn) = (apply #'append (maplist fun x1 ... xn))
  452. (Actually a bit more efficient that this would be.)
  453.  
  454. 7.9.1.
  455. ------
  456.  
  457. MULTIPLE-VALUES-LIMIT = 128
  458.  
  459. MULTIPLE-VALUE-LIST, MULTIPLE-VALUE-BIND, MULTIPLE-VALUE-SETQ are
  460. implemented as special forms and, as such, rather efficient.
  461.  
  462. The macro NTH-VALUE:
  463. (NTH-VALUE n form) returns the (n+1)st value (n>=0) of form.
  464.  
  465.  
  466.                         CHAPTER 8: Macros
  467.                         -----------------
  468.  
  469. No notes.
  470.  
  471.  
  472.                      CHAPTER 9: Declarations
  473.                      -----------------------
  474.  
  475. 9.2.
  476. ----
  477.  
  478. The declarations (TYPE type var ...), (FTYPE type fun ...),
  479. (FUNCTION name arglist result-type), (OPTIMIZE (quality value) ...)
  480. are ignored by the interpreter and the compiler.
  481.  
  482. Additional declarations:
  483.  
  484. * The declaration (COMPILE) has the effect that the current form is compiled
  485.   prior to execution.
  486.   Examples:
  487.   (LOCALLY (DECLARE (COMPILE)) form)
  488.   executes a compiled version of form.
  489.   (let ((x 0))
  490.     (flet ((inc () (declare (compile)) (incf x))
  491.            (dec () (decf x)))
  492.       (values #'inc #'dec)
  493.   ) )
  494.   returns two functions. The first is compiled and increments x, the second
  495.   is interpreted (slower) and decrements the same x.
  496.  
  497. 9.3.
  498. ----
  499.  
  500. The type assertion (THE value-type form) enforces a type check in
  501. interpreted code. No type check is done in compiled code.
  502.  
  503. If using the optional package MACROS3:
  504. (ETHE value-type form) enforces a type check in both interpreted and
  505. compiled code.
  506.  
  507.  
  508.                          CHAPTER 10: Symbols
  509.                          -------------------
  510.  
  511. No notes.
  512.  
  513.  
  514.                          CHAPTER 11: Packages
  515.                          --------------------
  516.  
  517. 11.6.
  518. -----
  519.  
  520. The package SYSTEM has the nicknames "SYS" and, additionally, "COMPILER".
  521.  
  522. 11.7.
  523. -----
  524.  
  525. The CLtL2 macro DEFPACKAGE is implemented.
  526.  
  527. 11.8.
  528. -----
  529.  
  530. The function REQUIRE receives as optional argument either a pathname or a
  531. list of pathnames: files to be loaded if the required module is not already
  532. in memory.
  533.  
  534.  
  535.                            CHAPTER 12: Numbers
  536.                            -------------------
  537.  
  538. The single and double float formats are those of the IEEE standard (1981),
  539. except that CLISP does not support features like +0, -0, +inf, -inf, gradual
  540. underflow, NaN, etc. (Common Lisp does not make use of these features.)
  541.  
  542. The default number of mantissa bits in long floats is given by the place
  543. (LONG-FLOAT-DIGITS).
  544. Example: (SETF (LONG-FLOAT-DIGITS) 3322) sets the default precision of long
  545. floats to 1000 decimal digits.
  546.  
  547. 12.1.
  548. -----
  549.  
  550. Complex numbers can have a real part and an imaginary part of different
  551. types. If the imaginary part is EQL to 0, the number is automatically
  552. converted to a real number. (Cf. CLtL1 p. 195)
  553. This has the advantage that  (let ((x (sqrt -9.0))) (* x x))
  554. - instead of evaluting to #C(-9.0 0.0), with x = #C(0.0 3.0) -
  555. evaluates to #C(-9.0 0) = -9.0, with x = #C(0 3.0).
  556.  
  557. Coercions on operations involving different types:
  558. The result of an arithmetic operation whose arguments are of different float
  559. types is rounded to the float format of the shortest (least precise) of the
  560. arguments.
  561.     rational -> long float -> double float -> single float -> short float
  562. (in contrast to CLtL1 p. 195!)
  563. Rationale:
  564.   See it mathematically. Add intervals:
  565.   {1.0 +/- 1e-8} + {1.0 +/- 1e-16} = {2.0 +/- 1e-8}
  566.   So, if we add 1.0s0 and 1.0d0, we should get 2.0s0.
  567. Shortly:
  568.   Do not suggest accuracy of a result by giving it a precision that is
  569.   greater than its accuracy.
  570. Example:
  571.   (- (+ 1.7 pi) pi)  should not return  1.700000726342836417234L0,
  572.   it should return 1.7f0 (or 1.700001f0 if there were rounding errors).
  573. Experience:
  574.   If in a computation using thousands of short floats, a long float (like pi)
  575.   happens to be used, the long precision should not propagate throughout all
  576.   the intermediate values. Otherwise, the long result would look precise,
  577.   but its accuracy is only that of a short float; furthermore much
  578.   computation time would be lost by calculating with long floats when only
  579.   short floats would be needed.
  580.  
  581. When rational numbers are to be converted to floats (due to FLOAT, COERCE,
  582. SQRT or a transcendental function), the result type is given by the variable
  583. *DEFAULT-FLOAT-FORMAT*.
  584.  
  585. 12.4.
  586. -----
  587.  
  588. (LCM), called without arguments, returns 1, which is the neutral element of
  589. composition with LCM.
  590.  
  591. (! n) returns the factorial of n, n a nonnegative integer.
  592.  
  593. (EXQUO x y) returns the quotient x/y of two integers x,y, and checks that it
  594. is an integer. (This is more efficient than /.)
  595.  
  596. 12.5.1.
  597. -------
  598.  
  599. (EXPT base exponent) is not very precise if exponent has large absolute
  600. value.
  601.  
  602. (LOG number base) signals an error if base = 1.
  603.  
  604. 12.5.2.
  605. -------
  606.  
  607. The value of PI is a long float with the precision given by
  608. (LONG-FLOAT-DIGITS). When this precision is changed, the value of PI is
  609. automatically recomputed. Therefore PI is a variable, not a constant.
  610.  
  611. 12.6.
  612. -----
  613.  
  614. FLOAT-RADIX always returns 2.
  615.  
  616. (FLOAT-DIGITS number digits) coerces `number' (a real number) to a floating
  617. point number with at least `digits' mantissa digits. The following holds:
  618.    (>= (FLOAT-DIGITS (FLOAT-DIGITS number digits)) digits)
  619.  
  620. 12.7.
  621. -----
  622.  
  623. BOOLE-CLR   =  0
  624. BOOLE-SET   = 15
  625. BOOLE-1     = 10
  626. BOOLE-2     = 12
  627. BOOLE-C1    =  5
  628. BOOLE-C2    =  3
  629. BOOLE-AND   =  8
  630. BOOLE-IOR   = 14
  631. BOOLE-XOR   =  6
  632. BOOLE-EQV   =  9
  633. BOOLE-NAND  =  7
  634. BOOLE-NOR   =  1
  635. BOOLE-ANDC1 =  4
  636. BOOLE-ANDC2 =  2
  637. BOOLE-ORC1  = 13
  638. BOOLE-ORC2  = 11
  639.  
  640. 12.10.
  641. ------
  642.  
  643. MOST-POSITIVE-FIXNUM = 2^24-1 = 16777215
  644. MOST-NEGATIVE-FIXNUM = -2^24 = -16777216
  645.  
  646. Together with PI, the other long float constants MOST-POSITIVE-LONG-FLOAT,
  647. LEAST-POSITIVE-LONG-FLOAT, LEAST-NEGATIVE-LONG-FLOAT,
  648. MOST-NEGATIVE-LONG-FLOAT, LONG-FLOAT-EPSILON, LONG-FLOAT-NEGATIVE-EPSILON
  649. are recomputed whenever (LONG-FLOAT-DIGITS) is changed. They are variables,
  650. not constants.
  651.  
  652.  
  653.                          CHAPTER 13: Characters
  654.                          ----------------------
  655.  
  656. See first above: 2.2.
  657.  
  658. 13.1.
  659. -----
  660.  
  661. CHAR-CODE-LIMIT = 256
  662. CHAR-FONT-LIMIT = 16
  663. CHAR-BITS-LIMIT = 16
  664.  
  665. 13.2.
  666. -----
  667.  
  668. String-chars are those characters with font = 0 and bits = 0.
  669.  
  670. The graphic characters have been described above.
  671.  
  672. The standard characters are #\Newline and those graphic characters with a
  673. code between 32 and 126 (inclusive).
  674.  
  675. The alphabetic characters are these string-chars:
  676.              ABCDEFGHIJKLMNOPQRSTUVWXYZ
  677.              abcdefghijklmnopqrstuvwxyz
  678. and the international alphabetic characters from the character set:
  679.              ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜßáíóúñѪºA etc.
  680.  
  681. The functions CHAR-EQUAL, CHAR-NOT-EQUAL, CHAR-LESSP, CHAR-GREATERP,
  682. CHAR-NOT-GREATERP, CHAR-NOT-LESSP ignore bits and font attributes of their
  683. arguments.
  684.  
  685. 13.4.
  686. -----
  687.  
  688. The string chars that are not graphic chars and the space character have
  689. names:
  690.   (code-char #x00) = #\Null
  691.   (code-char #x07) = #\Bell
  692.   (code-char #x08) = #\Backspace = #\Rubout
  693.   (code-char #x09) = #\Tab
  694.   (code-char #x0A) = #\Newline = #\Linefeed
  695.   (code-char #x0B) = #\Code11
  696.   (code-char #x0C) = #\Page
  697.   (code-char #x0D) = #\Return
  698.   (code-char #x1A) = #\Code26
  699.   (code-char #x1B) = #\Escape
  700.   (code-char #x20) = #\Space
  701.  
  702. 13.5.
  703. -----
  704.  
  705. CHAR-CONTROL-BIT = 1
  706. CHAR-META-BIT    = 2
  707. CHAR-SUPER-BIT   = 4
  708. CHAR-HYPER-BIT   = 8
  709.  
  710.  
  711.                          CHAPTER 14: Sequences
  712.                          ---------------------
  713.  
  714. 14.1.
  715. -----
  716.  
  717. The result of NREVERSE is always EQ to the argument. NREVERSE on a vector
  718. swaps pairs of elements. NREVERSE on a list swaps the first and the last
  719. element and reverses the list chaining between them.
  720.  
  721. 14.2.
  722. -----
  723.  
  724. For iteration through a sequence, a macro DOSEQ, analogous to DOLIST, may be
  725. used instead of MAP :
  726.   (doseq (var seqform [resultform]) {declaration}* {tag|statement}* )
  727.  
  728. 14.3.
  729. -----
  730.  
  731. REMOVE, REMOVE-IF, REMOVE-IF-NOT, REMOVE-DUPLICATES return their argument
  732. unchanged, if no element has to be removed.
  733.  
  734. DELETE, DELETE-IF, DELETE-IF-NOT, DELETE-DUPLICATES destructively modify
  735. their argument: If the argument is a list, the CDR parts are modified. If
  736. the argument is a vector with fill pointer, the fill pointer is lowered and
  737. the remaining elements are compacted below the new fill pointer.
  738.  
  739. 14.5.
  740. -----
  741.  
  742. SORT and STABLE-SORT have two additional keywords :START and :END :
  743.   (SORT sequence predicate &key :key :start :end)
  744.   (STABLE-SORT sequence predicate &key :key :start :end)
  745.  
  746. SORT and STABLE-SORT are identical. They implement the mergesort algorithm.
  747.  
  748.  
  749.                          CHAPTER 15: Lists
  750.                          -----------------
  751.  
  752. 15.4.
  753. -----
  754.  
  755. SUBLIS and NSUBLIS apply the :KEY argument to the nodes of the cons tree and
  756. not to the keys of the alist.
  757.  
  758.  
  759.                       CHAPTER 16: Hash Tables
  760.                       -----------------------
  761.  
  762. 16.1.
  763. -----
  764.  
  765. MAKE-HASH-TABLE has an additional keyword :INITIAL-CONTENTS :
  766.   (MAKE-HASH-TABLE &key :test :initial-contents :size :rehash-size
  767.                         :rehash-threshold)
  768. The :INITIAL-CONTENTS argument is an alist that is used to initialize the
  769. new hash table.
  770. The :REHASH-THRESHOLD argument is ignored.
  771.  
  772. For iteration through a hash table, a macro DOHASH, analogous to DOLIST, can
  773. be used instead of MAPHASH :
  774.   (dohash (key-var value-var hash-table-form [resultform])
  775.     {declaration}* {tag|statement}*
  776.   )
  777.  
  778.  
  779.                      CHAPTER 17: Arrays
  780.                      ------------------
  781.  
  782. 17.1.
  783. -----
  784.  
  785. ARRAY-RANK-LIMIT is 65536 on 16-bit processors, 4294967296 on 32-bit
  786. processors.
  787.  
  788. ARRAY-DIMENSION-LIMIT  = 2^24 = 16777216
  789. ARRAY-TOTAL-SIZE-LIMIT = 2^24 = 16777216
  790.  
  791. 17.6.
  792. -----
  793.  
  794. An array to which another array is displaced should not be shrunk (using
  795. ADJUST-ARRAY) in such a way that the other array points into void space.
  796. This is not checked at the time ADJUST-ARRAY is called!
  797.  
  798.  
  799.                        CHAPTER 18: Strings
  800.                        -------------------
  801.  
  802. 18.2.
  803. -----
  804.  
  805. String comparison is based on the function CHAR<=. Therefore diphtongs do
  806. not obey the usual national rules. Example: "o" < "oe" < "z" < "ö".
  807.  
  808.  
  809.                         CHAPTER 19: Structures
  810.                         ----------------------
  811.  
  812. 19.5.
  813. -----
  814.  
  815. The :PRINT-FUNCTION option should contain a lambda expression
  816.   (lambda (structure stream depth) (declare (ignore depth)) ...)
  817. This lambda expression names a function whose task is to output the external
  818. representation of structure onto the stream. This may be done by outputting
  819. text onto the stream using WRITE-CHAR, WRITE-STRING, WRITE, PRIN1, PRINC,
  820. PRINT, PPRINT, FORMAT and the like. The following rules must be obeyed:
  821. * The value of *PRINT-ESCAPE* must be respected.
  822. * The value of *PRINT-PRETTY* should not and cannot be respected, since the
  823.   pretty-print mechanism is not accessible from outside.
  824. * The value of *PRINT-CIRCLE* need not to be respected. This is managed by
  825.   the system. (But the print-circle mechanism handles only those objects that
  826.   are (direct or indirect) components of structure.)
  827. * The value of *PRINT-LEVEL* is respected by
  828.   WRITE, PRIN1, PRINC, PRINT, PPRINT, FORMAT ~A, FORMAT ~S, FORMAT ~W and
  829.   FORMAT ~D,~B,~O,~X,~R,~F,~E,~G,~$ with not-numerical arguments.
  830.   Therefore the print-level mechanism works automatically if only these
  831.   functions are used for outputting objects and if they are not called on
  832.   objects with nesting level > 1. (The print-level mechanism does not
  833.   recognize how many parentheses you have output. It only counts how many
  834.   times it was called recursively.)
  835. * The value of *PRINT-LENGTH* must be respected, especially if you are
  836.   outputting an arbitrary number of components.
  837. * You need not bother about the values of *PRINT-BASE*, *PRINT-RADIX*,
  838.   *PRINT-CASE*, *PRINT-GENSYM*, *PRINT-ARRAY*, *PRINT-CLOSURE*.
  839.  
  840. The :INHERIT option is exactly like :INCLUDE except that it doesn't create
  841. new accessors for the inherited slots. Use this option to avoid the problems
  842. that occur when using the same :CONC-NAME for the new and the inherited
  843. structure.
  844.  
  845.  
  846.                        CHAPTER 20: The Evaluator
  847.                        -------------------------
  848.  
  849. As in Scheme, the Macro (THE-ENVIRONMENT) returns the current lexical
  850. environment. This works only in interpreted code and is not compilable!
  851.  
  852. (EVAL-ENV form [env]) evaluates a form in a given lexical environment, just
  853. if the form had been part of the program text that environment came from.
  854.  
  855.  
  856.                          CHAPTER 21: Streams
  857.                          -------------------
  858.  
  859. 21.1.
  860. -----
  861.  
  862. *TERMINAL-IO* is not the only stream that communicates directly with the
  863. user: During execution of the body of a (WITH-KEYBOARD . body) form,
  864. *KEYBOARD-INPUT* is the stream that reads the keystrokes from the keyboard.
  865. It returns every keystroke in detail, as character with the following bits:
  866.   HYPER        if a non-standard key. These are:
  867.                  function keys, cursor keypads, numeric keypad.
  868.   CHAR-CODE    the Ascii code for standard keys,
  869.                for non-standard keys:
  870.                  F1 -> #\F1, ..., F10 -> #\F10, F11 -> #\F11, F12 -> #\F12,
  871.                  Insert -> #\Insert, Delete -> #\Delete,
  872.                  Home -> #\Home, End -> #\End, PgUp -> #\PgUp, PgDn -> #\PgDn,
  873.                  Arrow keys -> #\Up, #\Down, #\Left, #\Right.
  874.   SUPER        if pressed together with Shift key(s) and if the keystroke
  875.                would have been an other without Shift.
  876.   CONTROL      if pressed together with the Control key.
  877.   META         if pressed together with the Alternate key.
  878. This keyboard input is not echoed on the screen.
  879. During execution of a (WITH-KEYBOARD . body) form, no input from *TERMINAL-IO*
  880. or any synonymous stream should be requested.
  881.  
  882. 21.2.
  883. -----
  884.  
  885. The macro WITH-OUTPUT-TO-PRINTER
  886.        (with-output-to-printer (var) {declaration}* {form}*)
  887. binds the variable var to an output stream that sends its output to the
  888. printer.
  889.  
  890. (MAKE-PIPE-INPUT-STREAM command) returns an input stream that will supply the
  891. output from the execution of the given operating system command.
  892. See also (SHELL command).
  893.  
  894. (MAKE-PIPE-OUTPUT-STREAM command) returns an output stream that will pass its
  895. output as input to the execution of the given operating system command.
  896. See also (SHELL command).
  897.  
  898. 21.3.
  899. -----
  900.  
  901. CLOSE ignores its :ABORT argument.
  902.  
  903.  
  904.                      CHAPTER 22: Input/Output
  905.                      ------------------------
  906.  
  907. 22.1.2.
  908. -------
  909.  
  910. A "reserved token", i.e. a token that has potential number syntax but cannot
  911. be interpreted as a number, is interpreted as symbol when being read. (CLtL1
  912. p. 341)
  913.  
  914. When a token with package markers is read, then (CLtL1 p. 343/344) no
  915. checking is done whether the package part and the symbol-name part do not
  916. have number syntax. (What's the purpose of this check?) So we consider
  917. tokens like USER:: or :1 or LISP::4711 or 21:3 as symbols.
  918.  
  919. 22.1.3.
  920. -------
  921.  
  922. The backquote read macro also works when nested. Example:
  923.  (eval ``(,#'(lambda () ',a) ,#'(lambda () ',b)))
  924.  = (eval `(list #'(lambda () ',a) #'(lambda () ',b)))
  925.  = (eval (list 'list (list 'function (list 'lambda nil (list 'quote a)))
  926.                      (list 'function (list 'lambda nil (list 'quote b)))
  927.    )     )
  928.  
  929. Multiple backquote combinations like ,,@ or ,@,@ are not implemented. Their
  930. use would be confusing anyway.
  931.  
  932. 22.1.4.
  933. -------
  934.  
  935. #\ allows inputting characters of arbitrary code: #\Code231 yields the
  936. character (code-char 231.).
  937.  
  938. Additional read dispatch macros:
  939. * #Y is used to read compiled functions.
  940. * #" is used to read pathnames:
  941.      #"test.lsp" is the value of (pathname "test.lsp")
  942.      As in all strings, backslashes must be written twice here:
  943.      #"A:\\programs\\test.lsp"
  944.  
  945. 22.1.5.
  946. -------
  947.  
  948. Is it impossible to get the read macro function of a dispatch macro
  949. character like #\# using GET-MACRO-CHARACTER.
  950.  
  951. 22.1.6.
  952. -------
  953.  
  954. In absence of SYS::WRITE-FLOAT, floating point numbers are output in radix 2.
  955.  
  956. Pathnames are written according to the syntax #"namestring" if
  957. *PRINT-ESCAPE* /= NIL. If *PRINT-ESCAPE* = NIL, only the namestring is
  958. printed.
  959.  
  960. *PRINT-CASE* controls the output not only of symbols, but also of characters
  961. and some #<...> objects.
  962.  
  963. *PRINT-PRETTY* is initially = NIL.
  964.  
  965. *PRINT-ARRAY* is initially = T.
  966.  
  967. An additional variable *PRINT-CLOSURES* controls whether compiled and
  968. interpreted functions (closures) are output in detailed form. If
  969. *PRINT-CLOSURE* /= NIL, compiled closures are output in #Y syntax the reader
  970. understands. *PRINT-CLOSURE* is initially = NIL.
  971.  
  972. 22.3.1.
  973. -------
  974.  
  975. The functions WRITE and WRITE-TO-STRING have an additional keyword :CLOSURE
  976. that can be used to bind *PRINT-CLOSURE*.
  977.  
  978. The CLtL2 macro PRINT-UNREADABLE-OBJECT is implemented.
  979.  
  980. 22.3.3.
  981. -------
  982.  
  983. The FORMAT option ~W is analogous to ~A and ~S, but avoids binding of
  984. *PRINT-ESCAPE*. (FORMAT stream "~W" object) is equivalent to
  985. (WRITE object :stream stream).
  986.  
  987. FORMAT ~R and FORMAT ~:R can output only integers in the range |n| < 10^66.
  988. The output is in English, according to the American conventions, and these
  989. conventions are identical to the British conventions only in the range
  990. |n| < 10^9.
  991.  
  992. FORMAT ~:@C does not output the character itself, only the instruction how
  993. to type the character.
  994.  
  995. FORMAT ~T can determine the current column of any stream.
  996.  
  997.  
  998.                     CHAPTER 23: File System Interface
  999.                     ---------------------------------
  1000.  
  1001. 23.1.
  1002. -----
  1003.  
  1004. For most operations, pathnames denoting files and pathnames denoting
  1005. directories can not be used interchangeably.
  1006. This is especially important for the functions DIRECTORY, DIR, CD, MAKE-DIR,
  1007. DELETE-DIR.
  1008.  
  1009. The minimum filename syntax that may be used portably is:
  1010.   "xxx"       for a file with name xxx,
  1011.   "xxx.yy"    for a file with name xxx and type yy,
  1012.   ".yy"       for a pathname with type yy and no name specified.
  1013. Hereby xxx denote 1 to 8 characters, and yy denote 1 to 3 characters, each of
  1014. which being either alphanumerical or the underscore #\_.
  1015. Other properties of pathname syntax vary between operating systems.
  1016.  
  1017. 23.1.1.
  1018. -------
  1019.  
  1020. Pathname components:
  1021. HOST          always NIL
  1022. DEVICE        NIL or :WILD or "A"|...|"Z"
  1023. DIRECTORY     (startpoint . subdirs) where
  1024.                startpoint = :RELATIVE | :ABSOLUTE
  1025.                subdirs = () | (subdir . subdirs)
  1026.                subdir = :WILD (means "**" or "...", all subdirectories) or
  1027.                subdir = simple string, may contain wildcard characters ? and *
  1028. NAME          NIL or
  1029.               simple string, may contain wildcard characters ? and *
  1030.               (may also be specified as :WILD)
  1031. TYPE          NIL or
  1032.               simple string, may contain wildcard characters ? and *
  1033.               (may also be specified as :WILD)
  1034. VERSION       always NIL (may also be specified as :WILD or :NEWEST)
  1035.  
  1036. An OS/2 filename is split into name and type according to the following rule:
  1037.   if there is no '.' in the filename, then the name is everything, type = NIL;
  1038.   if there is a '.', then name is the part before and type the part after
  1039.      the last dot.
  1040.  
  1041. When a pathname is to be fully specified (no wildcards), that means that
  1042. no :WILD is allowed, no wildcard characters are allowed in the strings, and
  1043. NAME = NIL may not be allowed either.
  1044.  
  1045. External notation:       A:\sub1.typ\sub2.typ\name.typ
  1046. using defaults:            \sub1.typ\sub2.typ\name.typ
  1047. or                                            name.typ
  1048. or                       *:\sub1.typ\**\sub3.typ\x*.lsp
  1049. or similar.
  1050. Instead of '\' one may use '/', as usual for DOS calls.
  1051.  
  1052. The wildcard characters: '*' matches any sequence of characters,
  1053. '?' matches any one character.
  1054.  
  1055. Due to the name/type splitting rule, there are pathnames that can't result
  1056. from PARSE-NAMESTRING. To get a pathname whose type contains a dot or whose
  1057. name contains a dot and whose type is NIL, MAKE-PATHNAME must be used.
  1058. Example: (MAKE-PATHNAME :NAME ".profile").
  1059.  
  1060. 23.1.2.
  1061. -------
  1062.  
  1063. External notation of pathnames (cf. PARSE-NAMESTRING and NAMESTRING),
  1064. of course without spaces, [,],{,}:
  1065.  [ [drivespec]         a letter '*'|'A'|...|'Z'|'a'|...|'z'
  1066.    :
  1067.  ]
  1068.  { name [. type] \ }   each one a subdirectory, '\' may be replaced by '/'
  1069.  [ name [. type] ]     filename with type (extension)
  1070.  
  1071. Name and type may be character sequences of any length (consisting of
  1072. printing ASCII characters, except '/', '\', ':').
  1073.  
  1074. The function USER-HOMEDIR-PATHNAME is not implemented.
  1075.  
  1076. 23.2.
  1077. -----
  1078.  
  1079. The file streams returned by OPEN are always buffered.
  1080.  
  1081. 23.3.
  1082. -----
  1083.  
  1084. FILE-AUTHOR always returns NIL.
  1085.  
  1086. FILE-POSITION works on any file stream. When a Newline is output to resp.
  1087. input from a file stream, its file position is increased by 2 since Newline
  1088. is encoded as CR/LF in the file.
  1089.  
  1090. 23.4.
  1091. -----
  1092.  
  1093. LOAD has two additional keywords :ECHO and :COMPILING.
  1094. (LOAD filename &key :verbose :print :echo :if-does-not-exist :compiling)
  1095. :VERBOSE T   causes LOAD to emit a short message that a file is being loaded.
  1096.              The default is *LOAD-VERBOSE*, which is initially = T.
  1097. :PRINT T     causes LOAD to print the value of each form.
  1098.              The default is *LOAD-PRINT*, which is initially = NIL.
  1099. :ECHO T      causes the input from the file to be echoed to *STANDARD-OUTPUT*
  1100.              (normally to the screen). Should there be an error in the file,
  1101.              you can see at one glance where it is.
  1102.              The default is *LOAD-ECHO*, which is initially = NIL.
  1103. :COMPILING T causes each form read to be compiled on the fly. The compiled
  1104.              code is executed at once and - in contrast to COMPILE-FILE -
  1105.              not written to a file.
  1106.  
  1107. The variable *LOAD-PATHS* contains a list of directories where program files
  1108. are searched - additionally to the specified or current directory - by LOAD,
  1109. REQUIRE, COMPILE-FILE.
  1110.  
  1111. 23.5.
  1112. -----
  1113.  
  1114. (DIRECTORY [pathname [:full]]) can run in two modes:
  1115. * If pathname contains no name or type component, a list of all matching
  1116.   directories is produced.
  1117. * Otherwise a list of all matching files is returned. If the :FULL argument
  1118.   is /= NIL, this contains additional information: for each matching file
  1119.   you get a list of at least four elements
  1120.   (file-pathname file-truename file-write-date-as-decoded-time file-length).
  1121.  
  1122. (DIR [pathname]) is like DIRECTORY, but displays the pathnames instead of
  1123. returning them. (DIR) shows the contents of the current directory.
  1124.  
  1125. (CD [pathname]) manages the current device and the current directory.
  1126. (CD pathname) sets it, (CD) returns it.
  1127.  
  1128. (DEFAULT-DIRECTORY) is equivalent to (CD), (SETF (DEFAULT-DIRECTORY) pathname)
  1129. is equivalent to (CD pathname).
  1130.  
  1131. (MAKE-DIR directory-pathname) creates a new subdirectory.
  1132.  
  1133. (DELETE-DIR directory-pathname) removes an (empty) subdirectory.
  1134.  
  1135. (EXECUTE programfile arg1 arg2 ...)  executes an external program. Its name
  1136. is programfile. It is given the strings arg1, arg2, ... as arguments.
  1137.  
  1138. (SHELL [command])  calls the operating system's shell.
  1139. (SHELL) calls the shell for interactive use. (SHELL command) calls the shell
  1140. only for execution of the one given command.
  1141.  
  1142.  
  1143.                         CHAPTER 24: Errors
  1144.                         ------------------
  1145.  
  1146. 24.1.
  1147. -----
  1148.  
  1149. When an error occurred, you are in a break loop. You can evaluate forms as
  1150. usual. The HELP command (or help key if there is one) lists the available
  1151. debugging commands.
  1152.  
  1153.  
  1154.                   CHAPTER 25: Miscellaneous Features
  1155.                   ----------------------------------
  1156.  
  1157. 25.1.
  1158. -----
  1159.  
  1160. The compiler can be called not only by the functions COMPILE, COMPILE-FILE
  1161. and DISASSEMBLE, also by the declaration (COMPILE).
  1162.  
  1163. (COMPILE-FILE input-file [:output-file] [:listing] [:verbose] [:warnings])
  1164. compiles a file to bytecode.
  1165.     input-file                should be a pathname/string/symbol.
  1166. The :output-file argument     should be NIL or T or a pathname/string/symbol
  1167.                               or an output-stream. The default is T.
  1168. The :listing argument         should be NIL or T or a pathname/string/symbol
  1169.                               or an output-stream. The default is NIL.
  1170. The :warnings argument        specifies whether warnings should also appear
  1171.                               on the screen.
  1172. The :verbose argument         specifies whether error messages should also
  1173.                               appear on the screen.
  1174.  
  1175. The CLtL2 special form LOAD-TIME-VALUE is implemented. (LOAD-TIME-VALUE form)
  1176. is like (QUOTE #,form) except that the former can be generated by macros.
  1177.  
  1178. The CLtL2 function FUNCTION-LAMBDA-EXPRESSION is implemented.
  1179. (FUNCTION-LAMBDA-EXPRESSION function) returns information about the source
  1180. of an interpreted function: lambda-expression, lexical environment, name.
  1181.  
  1182. 25.2.
  1183. -----
  1184.  
  1185. No on-line documentation is available for the system functions (yet).
  1186.  
  1187. 25.3.
  1188. -----
  1189.  
  1190. (TRACE fun ...) makes the functions fun, ... traced. Syntax of fun:
  1191. Either a symbol:
  1192.        symbol
  1193. or a list of a symbol and some keywords and arguments (which must come in
  1194. pairs!):
  1195.        (symbol
  1196.          [:suppress-if form]   ; no trace output as long as form is true
  1197.          [:step-if form]       ; invokes the stepper as soon as form is true
  1198.          [:pre form]           ; evaluates form before calling the function
  1199.          [:post form]          ; evaluates form after return from the function
  1200.          [:pre-break-if form]  ; goes into the break loop before calling the
  1201.                                ; function if form is true
  1202.          [:post-break-if form] ; goes into the break loop after return from
  1203.                                ; the function if form is true
  1204.          [:pre-print form]     ; prints the values of form before calling the
  1205.                                ; function
  1206.          [:post-print form]    ; prints the values of form after return from
  1207.                                ; the function
  1208.          [:print form]         ; prints the values of form both before
  1209.                                ; calling and after return from the function
  1210.        )
  1211. In all these forms you can access
  1212.   the function itself               as *TRACE-FUNCTION*,
  1213.   the arguments to the function     as *TRACE-ARGS*,
  1214.   the function/macro call as form   as *TRACE-FORM*,
  1215. and after return from the function
  1216.   the list of return values from the function call  as *TRACE-VALUES*,
  1217. and you can leave the function call with specified values by using RETURN.
  1218.  
  1219. TRACE and UNTRACE are also applicable to functions (SETF symbol) and to macros,
  1220. but not to locally defined functions and macros.
  1221.  
  1222. The function INSPECT is not implemented.
  1223.  
  1224. The function ED calls the external editor specified by the variable *EDITOR*
  1225. (see config.lsp).
  1226. If using the optional package EDITOR:
  1227.   ED behaves like this only if the variable *USE-ED* is NIL.
  1228.   Otherwise ED uses an Emacs-like screen editor with multiple windows.
  1229.  
  1230. 25.4.1.
  1231. -------
  1232.  
  1233. The variable *DEFAULT-TIME-ZONE* contains the default time zone used by
  1234. ENCODE-UNIVERSAL-TIME and DECODE-UNIVERSAL-TIME. It is initially set to -1
  1235. (which means 1 hour east of Greenwich, i.e. Mid European Time).
  1236.  
  1237. The timezone in a decoded time must not necessarily be an integer, but (as
  1238. float or rational number) it should be a multiple of 1/4.
  1239.  
  1240. INTERNAL-TIME-UNITS-PER-SECOND = 100.
  1241.  
  1242. 25.4.2.
  1243. -------
  1244.  
  1245. The functions MACHINE-TYPE, MACHINE-VERSION, MACHINE-INSTANCE and
  1246. SHORT-SITE-NAME, LONG-SITE-NAME should be defined by every user in his
  1247. site-specific CONFIG.LSP file.
  1248.  
  1249. The variable *FEATURES* initially contains the symbols
  1250.    CLISP            ; this implementation
  1251.    COMMON-LISP
  1252.    CLTL1
  1253.    INTERPRETER
  1254.    COMPILER
  1255.    CLOS
  1256.    ATARI            ; if hardware = Atari ST/TT and operating system = TOS
  1257.    AMIGA            ; if hardware = Amiga and operating system = Exec/AmigaDOS
  1258.    DOS              ; if hardware = PC (clone)  and operating system = DOS
  1259.    OS/2             ; if hardware = PC (clone)  and operating system = OS/2
  1260.    PC386            ; if hardware = PC (clone) with a 386/486
  1261.    VMS              ; if hardware = VAX         and operating system = VMS
  1262.    UNIX             ; if                            operating system = Unix
  1263.                     ;                               (yes, in this case the
  1264.                     ;                               hardware is irrelevant!)
  1265.    language         ; same as the value of *LANGUAGE*
  1266.  
  1267. The constant *LANGUAGE* is a string containing the language in which the
  1268. system communicates with the user. A symbol of the same name is contained in
  1269. *FEATURES*. Possible values are (yet): ENGLISH, DEUTSCH, FRANCAIS.
  1270.  
  1271.  
  1272.                  CHAPTER 28: Common Lisp Object System
  1273.                  -------------------------------------
  1274.  
  1275. To use CLOS, do (USE-PACKAGE "CLOS").
  1276.  
  1277. The functions
  1278.   SLOT-VALUE, SLOT-BOUNDP, SLOT-MAKUNBOUND, SLOT-EXISTS-P,
  1279.   FIND-CLASS, (SETF FIND-CLASS), CLASS-OF, CALL-NEXT-METHOD, NEXT-METHOD-P,
  1280.   CLASS-NAME, (SETF CLASS-NAME), NO-APPLICABLE-METHOD, NO-NEXT-METHOD,
  1281.   FIND-METHOD, ADD-METHOD, REMOVE-METHOD, COMPUTE-APPLICABLE-METHODS,
  1282.   METHOD-QUALIFIERS, FUNCTION-KEYWORDS, SLOT-MISSING, SLOT-UNBOUND,
  1283.   PRINT-OBJECT, DESCRIBE-OBJECT, MAKE-INSTANCE, INITIALIZE-INSTANCE,
  1284.   REINITIALIZE-INSTANCE, SHARED-INITIALIZE,
  1285. the macros
  1286.   WITH-SLOTS, WITH-ACCESSORS, DEFCLASS, DEFMETHOD, DEFGENERIC,
  1287.   GENERIC-FUNCTION, GENERIC-FLET, GENERIC-LABELS,
  1288. the classes
  1289.   STANDARD-CLASS, STRUCTURE-CLASS, BUILT-IN-CLASS, STANDARD-OBJECT,
  1290.   STANDARD-GENERIC-FUNCTION, STANDARD-METHOD and all predefined classes,
  1291. and the method combination
  1292.   STANDARD
  1293. are implemented.
  1294.  
  1295. Deviations from CLtL2 chapter 28:
  1296.  
  1297. DEFCLASS : It *is* required that the superclasses of a class be defined before
  1298. the DEFCLASS form for the class is evaluated.
  1299.  
  1300. The REAL type is added to the predefined classes listed in table 28-1.
  1301.  
  1302. Only STANDARD method combination is implemented.
  1303.  
  1304. CALL-NEXT-METHOD cannot be called with arguments.
  1305.  
  1306. CALL-NEXT-METHOD and NEXT-METHOD-P are local macros, not local functions.
  1307. Use #'(lambda () (call-next-method)) instead of #'call-next-method if you
  1308. really need it as a function.
  1309.  
  1310. There is a generic function NO-PRIMARY-METHOD (analogous to
  1311. NO-APPLICABLE-METHOD) which is called when a generic function of the class
  1312. STANDARD-GENERIC-FUNCTION is invoked and no primary method on that generic
  1313. function is applicable.
  1314.  
  1315. GENERIC-FLET and GENERIC-LABELS are implemented as macros, not as special
  1316. forms.
  1317.  
  1318. The function ENSURE-GENERIC-FUNCTION is not implemented.
  1319.  
  1320. ADD-METHOD can put methods into other generic functions than the one the method
  1321. came from.
  1322.  
  1323. PRINT-OBJECT and DESCRIBE-OBJECT are only called on objects of type
  1324. STANDARD-OBJECT.
  1325.  
  1326. DESCRIBE-OBJECT should not call DESCRIBE recursively as this would produce
  1327. more information than is likely to be useful to a human reader.
  1328.  
  1329. DOCUMENTATION still has the CLtL1 implementation.
  1330.  
  1331. User-defined method combination is not supported.
  1332. The sections 28.1.7.3., 28.1.7.4., the macros DEFINE-METHOD-COMBINATION,
  1333. CALL-METHOD and the functions INVALID-METHOD-ERROR, METHOD-COMBINATION-ERROR,
  1334. METHOD-QUALIFIERS are not implemented.
  1335.  
  1336. The macro WITH-ADDED-METHODS is not implemented.
  1337.  
  1338. Redefining classes is not supported.
  1339. The sections 28.1.10., 28.1.10.1., 28.1.10.2., 28.1.10.3., 28.1.10.4. and the
  1340. function UPDATE-INSTANCE-FOR-REDEFINED-CLASS are not implemented.
  1341.  
  1342. Changing the class of a given instance is not supported.
  1343. The sections 28.1.11., 28.1.11.1., 28.1.11.2., 28.1.11.3. and the functions
  1344. CHANGE-CLASS, UPDATE-INSTANCE-FOR-DIFFERENT-CLASS, MAKE-INSTANCES-OBSOLETE are
  1345. not implemented.
  1346.  
  1347.  
  1348.                 CHAPTER 99: Platform specific Extensions
  1349.                 ----------------------------------------
  1350.  
  1351. 99.2. Random Screen Access
  1352. --------------------------
  1353.  
  1354. (SCREEN:MAKE-WINDOW)
  1355.   returns a "window stream". As long as this stream is open, the terminal
  1356.   is in cbreak/noecho mode. *TERMINAL-IO* shouldn't be used for input or
  1357.   output during this time. (Use WITH-KEYBOARD and *KEYBOARD-INPUT* instead.)
  1358.  
  1359. (SCREEN:WITH-WINDOW . body)
  1360.   binds SCREEN:*WINDOW* to a window stream and executes body. The stream is
  1361.   guaranteed to be closed when the body is left. During its execution,
  1362.   *TERMINAL-IO* shouldn't be used, as above.
  1363.  
  1364. (SCREEN:WINDOW-SIZE window-stream)
  1365.   returns the window's size, as two values:
  1366.   height (= Ymax+1) and width (= Xmax+1).
  1367.  
  1368. (SCREEN:WINDOW-CURSOR-POSITION window-stream)
  1369.   returns the position of the cursor in the window, as two values:
  1370.   line (>=0, <=Ymax, 0 means top), column (>=0, <=Xmax, 0 means left margin).
  1371.  
  1372. (SCREEN:SET-WINDOW-CURSOR-POSITION window-stream line column)
  1373.   sets the position of the cursor in the window.
  1374.  
  1375. (SCREEN:CLEAR-WINDOW window-stream)
  1376.   clears the window's contents and puts the cursor in the upper left corner.
  1377.  
  1378. (SCREEN:CLEAR-WINDOW-TO-EOT window-stream)
  1379.   clears the window's contents from the cursor position to the end of window.
  1380.  
  1381. (SCREEN:CLEAR-WINDOW-TO-EOL window-stream)
  1382.   clears the window's contents from the cursor position to the end of line.
  1383.  
  1384. (SCREEN:DELETE-WINDOW-LINE window-stream)
  1385.   removes the cursor's line, moves the lines below it up by one line and
  1386.   clears the window's last line.
  1387.  
  1388. (SCREEN:INSERT-WINDOW-LINE window-stream)
  1389.   inserts a line at the cursor's line, moving the lines below it down by
  1390.   one line.
  1391.  
  1392. (SCREEN:HIGHLIGHT-ON window-stream)
  1393.   switches highlighted output on.
  1394.  
  1395. (SCREEN:HIGHLIGHT-OFF window-stream)
  1396.   switches highlighted output off.
  1397.  
  1398. (SCREEN:WINDOW-CURSOR-ON window-stream)
  1399.   makes the cursor visible, a cursor block in most implementations.
  1400.  
  1401. (SCREEN:WINDOW-CURSOR-OFF window-stream)
  1402.   makes the cursor invisible, in implementations where this is possible.
  1403.  
  1404.  
  1405. Authors:
  1406. --------
  1407.  
  1408.         Bruno Haible                    Michael Stoll
  1409.         Augartenstraße 40               Gallierweg 39
  1410.     D - 76137 Karlsruhe             D - 53117 Bonn
  1411.         Germany                         Germany
  1412.  
  1413. Email:  haible@ma2s2.mathematik.uni-karlsruhe.de
  1414.